Conditional Data Sites in an Html Template

Overview

Sapphire now supports the use of conditional data sites. To set up a conditional data site, you need to add to matching data sites.

The opening site looks like this:

##Sa_IF=condname##

where condname is the string that will be used to set the condition.

The closing site look like this:

##Sa_ENDIF=condname##

Once a matching pair has been established, the text in between these will only be output if the condition is set in code.

The function call:

SaSiteSetVar("condname", 1);

will set this condition to true.

The function call:

SaSiteSetVar("condname", 0);

will set this condition to false.

An alternate markup is the inverse of the above. To use this, the opening site should look like this:

##Sa_NOT=condname##

The closing site would be the same as above:

##Sa_ENDIF=condname##

Once this alternate condition is set, the text in between these will be output, unless the condition is set to false.

New API Functions

: 1. Three new API functions are used to output data correctly whether from CGI, an application server, an ORACLE cartridge, or other source. These new API calls are:

SaPrintf
SaFprintf
SaGetenv

: They have the same semantics and arguments that the corresponding C library functions do.
: 2. Three API functions that were not documented in previous releases are now described. These functions control the "playing" of HTML template files and are:

SaPlayHtmlList
SaResetHtmlList
SaAddHtmlTemp

: The last one takes a string argument which is the file name of the file to add to the play list. The first 2 should be obvious.
: 3. Three more API functions have been added to allow for conditional data sites in a template. They are:

SaSiteSetVar
SaSiteGetVar
SaSetSiteHook


a.	 The first was described above in the section on Conditional Data sites.

b.	 The second returns the state of the conditional variable determined by its string argument. 

c.	 The last allows you to "hook" into the logic for processing sites. You install a callback function of the type:

typdef int (*SaSiteHook) (char* sitename);


 The function receives the current site "name" (that is what is between ##Sa and ##) as its argument. A non-zero value return from your hook function will mean that the site has been fully processed by your function and Sapphire/Web will do no further processing. A zero value will indicate to Sapphire that it should continue processing in its usual manner. Notice that conditional sites and loops will have already been processed and your hook function will not be called.

API Changes

Conversion

Upgrading an existing project to Version 3.0 may require no code changes. Just load it into Sapphire/Web, change a few options, perform a few manual steps, and that's it. Some code changes may be necessary, however. These changes fall into the category of sending output from a CGI, memory cleanup, and getting standard CGI environment variables. For a CGI, you can simply write to standard output to send back data. If you have used the Sapphire/Web API (Sa....) then this has been hidden from you. If on the other hand you have used functions like:

printf
fprintf

then you will need to change these to:

SaPrintf
SaFprintf

These new functions (found in SaApi.h) take the same parameters as the standard C functions but will send output correctly whether the Sapphire server application is a CGI, Web Cartridge, NSAPI, ISAPI, or whatever. Other standard C output functions should be converted to an (Sa... function).

Memory Management

For a CGI, you can fail to free memory because the CGI will exit and clean up for you. For a Web Cartridge, NSAPI, ISAPI, or whatever application, which is a continually running process servicing many requests, memory should be free'd between requests. You could make sure that your code cleans up after itself. If you cannot do so due to limitations that Sapphire generated CGI's produce, you could switch your memory allocation calls to

SaMalloc

which takes the same parameters as malloc. Memory allocated with this call should not then be free'd, since Sapphire will clean up this memory after each request. The call SaFree can be used to clean up allocated memory sooner, if that is needed, but in general using SaMalloc will require no cleaning up. Note you should never mix calls to malloc/free and SaMalloc/SaFree.

Environment

From a CGI you can use getenv to retrieve standard CGI environment variables. For a Web Cartridge, NSAPI, ISAPI, or whatever application this will not work. Use the function SaGetenv as a replacement. It takes the same parameters as getenv. For other kinds of environment variables, like the PATH, you should continue to use getenv.

[Top] [Prev] [Next] [Bottom] [Contents]

info@bluestone.com